home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / dde / _pc / h / wimpt < prev    next >
Text File  |  1992-04-30  |  8KB  |  242 lines
  1. (*
  2.  * Title  : wimpt.h
  3.  * Purpose: provides low-level wimp functionality
  4.  *
  5.  *)
  6.  
  7. # ifndef __wimpt_h
  8. # define __wimpt_h
  9.  
  10. # ifndef __wimp_h
  11. # include "wimp.h"
  12. # endif
  13.  
  14. # ifndef __os_h
  15. # include "os.h"
  16. # endif
  17.  
  18. (* ------------------------------ wimpt_poll -------------------------------
  19.  * Description:   Poll for an event from the wimp (with extras to buffer
  20.  *                one event).
  21.  *
  22.  * Parameters:    wimp_emask mask -- ignore events in the mask
  23.  *                wimp_eventstr *result -- the event returned from wimp
  24.  * Returns:       possible error condition.
  25.  * Other Info:    If you want to poll at this low level (ie avoiding
  26.  *                event_process()), then use this function rather than
  27.  *                wimp_poll. Using wimpt_poll allows you to use the routines
  28.  *                shown below. 
  29.  *
  30.  *)
  31. procedure wimpt_poll(mask : wimp_emask;
  32.                 result : wimp_eventstr_ptr) : error; extern;
  33.  
  34.  
  35. (* -------------------------- wimpt_fake_event -----------------------------
  36.  * Description:   Post an event to be collected by wimpt_poll.
  37.  *
  38.  * Parameters:    wimp_eventstr * -- the posted event
  39.  * Returns:       void
  40.  * Other Info:    use with care!
  41.  *
  42.  *)
  43. procedure wimpt_fake_event(event : wimp_eventstr_ptr); extern;
  44.  
  45.  
  46. (* ----------------------------- wimpt_last_event --------------------------
  47.  * Description:   Informs caller of last event returned by wimpt_poll.
  48.  *
  49.  * Parameters:    void
  50.  * Returns:       pointer to last event returned by wimpt_poll.
  51.  * Other Info:    none.
  52.  *
  53.  *)
  54. function wimpt_last_event : wimp_eventstr_ptr; extern;
  55.  
  56.  
  57. (* ---------------------- wimpt_last_event_was_a_key -----------------------
  58.  * Description:   Informs caller if last event returned by wimpt_poll was
  59.  *                a key stroke.
  60.  *
  61.  * Parameters:    void
  62.  * Returns:       non-zero if last event was a keystroke.
  63.  * Other Info:    retained for compatibility with old world. 
  64.  *                Use wimpt_last_event by preference, and test
  65.  *                if e field of returned struct == wimp_EKEY.
  66.  *
  67.  *)
  68. function wimpt_last_event_was_a_key : integer; extern;
  69.  
  70.  
  71. (* ------------------------------ wimpt_noerr ------------------------------
  72.  * Description:   Halts program and reports error in dialogue box (if e!=0).
  73.  *
  74.  * Parameters:    os_error *e -- error return from system call
  75.  * Returns:       void.
  76.  * Other Info:    Useful for "wrapping up" system calls which are not
  77.  *                expected to fail; if so your program probably has a
  78.  *                logical error. Call when an error would mean disaster!! 
  79.  *                    eg. wimpt_noerr(some_system_call(.......));
  80.  *                Error message is : "<ProgName> has suffered a fatal 
  81.  *                internal error (<errormessage>) and must exit immediately".
  82.  *
  83.  *)
  84. procedure wimpt_noerr(e : error); extern;
  85.  
  86.  
  87. (* ----------------------------- wimpt_complain ----------------------------
  88.  * Description:   Reports error in dialogue box (if e!=0).
  89.  *
  90.  * Parameters:    os_error *e -- error return from system call
  91.  * Returns:       the error returned from the system call (ie. e).
  92.  * Other Info:    Useful for "wrapping up" system calls which may fail. Call
  93.  *                when your program can still limp on regardless (taking
  94.  *                some appropriate action).
  95.  *
  96.  *)
  97. procedure wimpt_complain(e : error) : error; extern;
  98.  
  99.  
  100.  
  101. (* -------- Control of graphics environment -------- *)
  102.  
  103.  
  104. (* -------------------------- wimpt_checkmode ----------------------------
  105.  * Description:   Registers with the wimpt module the current screen
  106.  *                mode. 
  107.  * 
  108.  * Parameters:    void
  109.  * Returns:       TRUE if screen mode has changed.
  110.  * Other Info:    none.
  111.  *
  112.  *)
  113. procedure wimpt_checkmode : boolean; extern;
  114.  
  115.  
  116. (* --------------------------- wimpt_mode --------------------------------
  117.  * Description:   Reads the screen mode
  118.  *
  119.  * Parameters:    void
  120.  * Returns:       screen mode.
  121.  * Other Info:    faster than a normal OS call. Value is only valid if
  122.  *                wimpt_checkmode is called at redraw events.
  123.  *
  124.  *)
  125. function wimpt_mode : integer; extern;
  126.  
  127.  
  128. (* ---------------------- wimpt_dx/wimpt_dy ------------------------------
  129.  * Description:   Inform caller of OS x/y units per screen pixel
  130.  *
  131.  * Parameters:    void
  132.  * Returns:       OS x/y units per screen pixel.
  133.  * Other Info:    faster than a normal OS call. Value is only valid if
  134.  *                wimpt_checkmode is called at redraw events.
  135.  *
  136.  *)
  137. function wimpt_dx : integer; extern;
  138. function wimpt_dy : integer; extern; 
  139.  
  140.  
  141. (* -------------------------- wimpt_bpp ----------------------------------
  142.  * Description:   Informs caller of bits per screen pixel.
  143.  *
  144.  * Parameters:    void
  145.  * Returns:       bits per screen pixel (in current mode).
  146.  * Other Info:    faster than a normal OS call. Value is only valid if
  147.  *                wimpt_checkmode is called at redraw events.
  148.  *
  149.  *)
  150. function wimpt_bpp : integer; extern;
  151.  
  152.  
  153. (* --------------------------- wimpt_init --------------------------------
  154.  * Description:   Set program up as a WIMP task.
  155.  *
  156.  * Parameters:    char *programname -- name of your program
  157.  * Returns:       int -- the current wimp version number.
  158.  * Other Info:    Remembers screen mode, and sets up signal handlers
  159.  *                so that task exits cleanly, even after fatal errors.
  160.  *                Response to signals SIGABRT, SIGFPE, SIGILL, SIGSEGV
  161.  *                SIGTERM is to display error box with message:
  162.  *                "<progname> has suffered an internal error (type =
  163.  *                <signal>) and must exit immediately"
  164.  *                SIGINT (Escape) is ignored. Progname will appear in the
  165.  *                task manager display and in error messages.
  166.  *                Calls wimp_taskinit and stores task_id returned
  167.  *                Also installs exit-handler to close down task when
  168.  *                program calls exit() function.
  169.  *
  170.  *)
  171. procedure wimpt_init(programname : string) : integer; extern;                
  172.  
  173.  
  174. (* --------------------------- wimpt_wimpversion ---------------------------
  175.  * Description:   Tell wimpt what version of the wimp you understand.
  176.  *
  177.  * Parameters:    int -- the version number of the wimp that you understand.
  178.  * Returns:       void.
  179.  * Other Info:    Call this routine before calling wimpt_init, if you
  180.  *                know about the features in a Wimp beyond version 2.00.
  181.  *                This argument will then be passed to wimp_init, allowing
  182.  *                the Wimp to understand what facilities you know about.
  183.  *                Then call wimpt_init, allowing the wimp to return
  184.  *                its current version number.
  185.  *
  186.  *)
  187. procedure wimpt_wimpversion(version : integer); extern;
  188.  
  189.  
  190. (* ----------------------------- wimpt_programname -----------------------
  191.  * Description:   Informs the caller of name passed to wimpt_init
  192.  *
  193.  * Parameters:    void
  194.  * Returns:       the program's name (pointer to).
  195.  * Other Info:    none.
  196.  *
  197.  *)
  198. function wimpt_programname : pointer; extern;
  199.  
  200.  
  201. (* -------------------------- wimpt_reporterror --------------------------
  202.  * Description:   Reports an OS error in a dialogue box.
  203.  *                (including program name)
  204.  *
  205.  * Parameters:    os_error* -- OS error block
  206.  *                wimp_errflags -- flag whether to include OK and/or
  207.  *                                 CANCEL(highlighted or not) button
  208.  *                                 in dialogue box
  209.  * Returns:       void.
  210.  * Other Info:    similar to wimp_reporterror(), but includes prog. name
  211.  *                automatically (eg. the one passed to wimpt_init).
  212.  *
  213.  *)
  214. procedure wimpt_reporterror(e : error; flags : wimp_errflags); extern;
  215.  
  216.  
  217. (* ----------------------------- wimpt_task ------------------------------
  218.  * Description:   Informs caller of its task handle.
  219.  *
  220.  * Parameters:    void
  221.  * Returns:       task handle.
  222.  * Other Info:    none.
  223.  *
  224.  *)
  225. function wimpt_task : wimp_t; extern;
  226.  
  227.  
  228. (* ----------------------------- wimpt_forceredraw -----------------------
  229.  * Description:   Causes whole screen to be invalidated (ie. running
  230.  *                applications will be requested to redraw all windows)
  231.  *
  232.  * Parameters:    void
  233.  * Returns:       void.
  234.  * Other Info:    none.
  235.  *
  236.  *)
  237. procedure wimpt_forceredraw; extern;
  238.  
  239. #endif
  240.  
  241. (* end wimpt.h *)
  242.